PikeApps/Pike ScriptRunner

Because ScriptRunner uses FastCGI, its performance should be close to embedded language solutions like mod_perl, but with a lot less worries about security and overflows. With ScriptRunner you can introduce all of your friends to Pike without forcing them to suffer bad performance or (more likely) give up their attachment to Apache. In addition, ScriptRunner does a lot of the unpleasant work of parsing incoming requests, allowing you to get right to the task of writing your code.

Right now, it's pretty early on in its development, so there are a lot of niceties present in Roxen or Caudium that aren't available, and it's not terribly well tested, so it could have some nasty bugs. Enough raw functionality is available to be highly useful; hopefully there will be interest in improving things in this area. ScriptRunner contains code written by others over the years; this is really more of a gathering of snippets into something more readily useful to others.

1. Install and configure FastCGI support for your webserver so that *.fcgi files are treated as FastCGI applications.

Simply copy the scriptrunner files to a FastCGI enabled web server (it's recommended that you just copy the whole ScriptRunner directory).

2a. Edit the ScriptRunner.fcgi file, making sure that the path to Pike is correct, and that the full path to the ScriptRunner directory is specified as the option to -M, without any spaces.

2b. While editing the scriptrunner application, specify an optional log file (recommended).

3. Add a redirect to convert all requests to (*.pike) to /path/to/scriptrunner.fcgi($1) (actual syntax will vary based on the redirector you're using.

For example, if I've installed ScriptRunner so that the ScriptRunner.fcgi is called by the following request:

www.mysite.com/path/to/ScriptRunner.fcgi

and I put a pike script in /some/other/path.pike on my website, I need my redirect to internally change

www.mysite.com/some/other/path.pike

www.mysite.com/path/to/ScriptRunner.fcgi/some/other/path.pike

This is a common technique used by PHP and other languages. Alternately, you could use mod_actions to do the same thing:

   AddHandler scriptrunner-pike-script .pike
   AddHandler scriptrunner-pike-script .psp
   Action scriptrunner-pike-script /path/to/ScriptRunner.fcgi

ScriptRunner can be run in either single or multithreaded mode. Basically, this means that you can either have one thread processing all requests, or have a set of threads processing requests concurrently. Note that multithreaded operation doesn't necessarily mean that your scripts will run faster. In fact, single threaded operation tends to run about 4-5% faster on simple requests. You may find multithreading useful when performing large numbers of operations such as Image manipulations or SQL transactions, which are typically performed in C libraries, which often allow concurrent operations.

To enable (or disable) threaded operation, simply uncomment (or comment) the line in ScriptRunner.fcgi that looks like this:

#define RUN_THREADED

And restart ScriptRunner.fcgi (which may involve restarting your web server software). You can verify that ScriptRunner is running in single or multithreaded mode by making multiple requests to ScriptRunner.fcgi without a file argument. The first line following the version will indicate the thread handling the request. If the thread changes, you're running multiple handler threads; if it stays zero (0) across multiple requests, you're in singlethreaded mode.

Pike scripts look a lot like C or Java, but the first thing you'll notice is that they're far less verbose. One of the nice things about Pike is that a lot of powerful language constructs and methods are available to you out of the box. For example, the following script will render the contents of the form variable "input" as text on a PNG image:

mapping parse(object id)
{
  // note that all of the most commonly used pieces of the request are
  // assembled in the request id object. 
  if(!id->variables->input)
    id->variables->input = "Default Text";   // the last argument is set to 1 to ensure we get a font back, even
   // if we don't have the one we're looking for.
  object fnt = Image.Fonts.load_font("Times New Roman", 72, 0, 1);
  object img = fnt->write(id->variables->input);
  string output = Image.PNG.encode(img);
  return (["data": output, "type": "image/png"]);
}

The following example demonstrates Pike's database-independent SQL API. In this example, we're running a database query and returning the results as a table. Also note that we've added some code to speed processing: we keep the database connection open between requests.

object sql;
string sql_url = "mysql://user:pass@localhost/mydb";
string parse(object id)
{
  if(!sql)
    sql = connect_sql(sql_url);
  // note that we use 'sprintf' like features here. the replacement variables
  // get automatically quoted as appropriate for the underlying database.
  // we're also using the 'simple query' interface that returns the result
  // as an array of mappings (hashes)
  array sql_result = sql->query("SELECT firstname, lastname, phone FROM addresses WHERE lastname like %s", "Smith%");
  if(!sizeof(sql_result))
    return "sorry, there were no entries.";
  String.Buffer r = String.Buffer();
  // In addition to standard object oriented method calls, 
  // Pike supports operator overloading, which allows objects to
  // appear as though they were simple datatypes. This allows us to
  // start with strings, and very simply replace the more efficient
  // string buffer object, with only 2 changes to our code
  r += "<table>";
  // let's loop through the result set
  foreach(sql_result; int index; mapping row)
    r += sprintf("<tr><td>%s, %s</td><td>%s</td></tr>", 
                 row->lastname, row->firstname, row->phone);
  r+="</table>";
  // we could have just as easily cast the buffer to a string.
  return r->get();
}
object connect_sql(string url)
{
  object s;
  if(catch(s = Sql.Sql(url)))
    throw(Error.Generic("Unable to connect to the database.&#110;"));
  return s;
}

Some example scripts (they all start with test) are included to give you a head start. More extensive documentation is available in the source distribution.

As of version 0.3, ScriptRunner supports session state persistence. Currently the session storage engine uses a hash directory and serialization files, which means that it's not optimized for performance. Additional engines are welcome, some potential options include: RAM, SQL and Memcache.

To use sessions in your Pike Script, simply add an integer "__participates_in_session" with a value of 1. See the class ScriptRunner.SRPikeScript for details. If this value is set, ScriptRunner will create a session cookie (if necessary), and retrieve any previously set session variables. The session information can be found within the following mapping in your RequestID object:

request->misc->session_variables

request->misc->session_id

Simply place any data (no objects or programs yet, please!) you wish to persist into this mapping, and it will be saved between requests. Do note that the more data you place into this mapping, the slower your session will run, as it must be (currently serialized) and saved between requests.

30/Sept/2005: There's a misfeature in the PSP handler that currently ignores any text before the first psp tag. Fixed in CVS, please download a tarball from the repository (see above).

Pike ScriptRunner is free software made available under the GPL/LGPL/MPL licenses. We're just getting started, so we're not totally organized yet. For the time being, send email to the Pike mailing list: pike at roxen dot com or to the author: bill at gotpike dot org.